package com.zenithmind.note.service;

import com.zenithmind.common.result.PageResult;
import com.zenithmind.note.pojo.entity.Note;
import com.zenithmind.note.pojo.query.NoteQuery;
import com.zenithmind.note.pojo.vo.NoteVO;
import com.zenithmind.note.pojo.vo.NoteTagVO;

import java.util.List;
import java.util.Map;

/**
 * 笔记查询服务接口
 * 遵循单一职责原则：只负责笔记查询相关的业务逻辑
 * 遵循接口隔离原则：将查询操作从主服务中分离
 * 
 * @author ZenithMind
 * @since 2024-01-01
 */
public interface NoteQueryService {
    
    /**
     * 根据ID获取笔记实体
     * 
     * @param id 笔记ID
     * @return 笔记实体
     */
    Note getNoteById(String id);
    
    /**
     * 获取笔记详情VO
     * 
     * @param id 笔记ID
     * @param userId 用户ID（用于判断点赞状态等）
     * @return 笔记详情VO
     */
    NoteVO getNoteDetail(String id, String userId);
    
    /**
     * 分页查询笔记列表
     * 
     * @param query 查询条件
     * @return 分页结果
     */
    PageResult<NoteVO> queryNotePage(NoteQuery query);
    
    /**
     * 获取用户的笔记列表
     * 
     * @param userId 用户ID
     * @param current 当前页
     * @param size 每页大小
     * @return 分页结果
     */
    PageResult<NoteVO> getUserNotes(String userId, long current, long size);
    
    /**
     * 获取笔记的标签列表
     * 
     * @param noteId 笔记ID
     * @return 标签列表
     */
    List<NoteTagVO> getNoteTagList(String noteId);
    
    /**
     * 获取热门笔记列表
     * 
     * @param limit 数量限制
     * @return 热门笔记列表
     */
    List<NoteVO> getHotNotes(int limit);
    
    /**
     * 获取最新笔记列表
     * 
     * @param limit 数量限制
     * @return 最新笔记列表
     */
    List<NoteVO> getLatestNotes(int limit);
    
    /**
     * 搜索笔记
     * 
     * @param keyword 关键词
     * @param current 当前页
     * @param size 每页大小
     * @return 搜索结果
     */
    PageResult<NoteVO> searchNotes(String keyword, long current, long size);
    
    /**
     * 获取相关推荐笔记
     * 
     * @param noteId 笔记ID
     * @param limit 数量限制
     * @return 推荐笔记列表
     */
    List<NoteVO> getRelatedNotes(String noteId, int limit);
    
    /**
     * 获取标签使用统计
     * 
     * @return 标签统计列表
     */
    List<Map<String, Object>> getTagsWithCount();
    
    /**
     * 判断笔记是否存在
     * 
     * @param id 笔记ID
     * @return 是否存在
     */
    boolean noteExists(String id);
    
    /**
     * 判断用户是否有权限访问笔记
     * 
     * @param noteId 笔记ID
     * @param userId 用户ID
     * @return 是否有权限
     */
    boolean hasAccessPermission(String noteId, String userId);
}
